// Package audioplayer 提供统一的音频播放接口和实现
package audioplayer

import (
	"context"
	"io"
	"time"
)

// AudioFormat 表示音频格式
type AudioFormat string

// 支持的音频格式
const (
	FormatMP3  AudioFormat = "mp3"
	FormatWAV  AudioFormat = "wav"
	FormatOGG  AudioFormat = "ogg"
	FormatFLAC AudioFormat = "flac"
	FormatAAC  AudioFormat = "aac"
	FormatRAW  AudioFormat = "raw"
)

// PlaybackStatus 表示播放状态
type PlaybackStatus string

// 播放状态常量（强调持续性）
const (
	StatusPlaying PlaybackStatus = "playing"
	StatusPaused  PlaybackStatus = "paused"
	StatusStopped PlaybackStatus = "stopped"
	StatusError   PlaybackStatus = "error"
)

// PlaybackEventType 表示播放事件类型
type PlaybackEventType int

// 播放事件类型常量（强调瞬态，状态的变更，理解为拐点）
const (
	EventPlaybackStarted PlaybackEventType = iota
	EventPlaybackPaused
	EventPlaybackResumed
	EventPlaybackStopped   // 认为结束
	EventPlaybackCompleted // 自然结束，播放位置或者进度为100%或极度接近
	EventPlaybackError
	EventPositionChanged
)

// AudioSource 表示音频源
type AudioSource struct {
	// 音频源的路径或URL
	Path string
	// 音频格式，可选，如果为空则尝试从Path推断
	Format AudioFormat
	// 音频名称，可选，用于显示
	Name string
	// 是否是流媒体
	IsStream bool
	// 流媒体读取器，当IsStream为true时使用
	Stream io.Reader
	// 额外元数据
	Metadata map[string]string
}

// PlaybackInfo 包含播放相关信息
type PlaybackInfo struct {
	// 当前状态
	Status PlaybackStatus
	// 当前播放的音频源
	Source *AudioSource
	// 播放位置（秒）
	Position float64
	// 总时长（秒），-1表示未知
	Duration float64
	// 音量（0.0-1.0）
	Volume float64
	// 是否循环播放
	IsLooping bool
	// 错误信息，如果状态为StatusError
	Error string
}

// PlaybackEvent 表示播放事件
type PlaybackEvent struct {
	// 事件类型
	Type PlaybackEventType
	// 播放信息
	Info PlaybackInfo
	// 发生时间
	Timestamp time.Time
}

// PlaybackEventHandler 播放事件处理函数类型
type PlaybackEventHandler func(event PlaybackEvent)

// AudioPlayer 定义音频播放器接口
type AudioPlayer interface {
	// 基本播放控制

	// Play 播放指定音频源
	Play(ctx context.Context, source AudioSource) error

	// Pause 暂停当前播放
	Pause(ctx context.Context) error

	// Resume 恢复播放
	Resume(ctx context.Context) error

	// Stop 停止播放
	Stop(ctx context.Context) error

	// IsPlaying 返回当前是否正在播放
	IsPlaying() bool

	// 播放列表管理

	// AddToPlaylist 添加音频源到播放列表
	AddToPlaylist(source AudioSource) error

	// RemoveFromPlaylist 从播放列表移除指定音频源
	RemoveFromPlaylist(index int) error

	// ClearPlaylist 清空播放列表
	ClearPlaylist() error

	// GetPlaylist 获取当前播放列表
	GetPlaylist() ([]AudioSource, error)

	// PlayNext 播放列表中的下一个
	PlayNext(ctx context.Context) error

	// PlayPrevious 播放列表中的上一个
	PlayPrevious(ctx context.Context) error

	// 播放进度控制

	// Seek 跳转到指定位置（秒）
	Seek(ctx context.Context, position float64) error

	// GetPosition 获取当前播放位置（秒）
	GetPosition() float64

	// GetDuration 获取当前音频总长度（秒）
	GetDuration() float64

	// GetPlaybackInfo 获取完整的播放信息
	GetPlaybackInfo() PlaybackInfo

	// 音量控制

	// SetVolume 设置音量（0.0-1.0）
	SetVolume(volume float64) error

	// GetVolume 获取当前音量
	GetVolume() float64

	// 事件处理

	// RegisterEventHandler 注册事件处理函数
	RegisterEventHandler(eventType PlaybackEventType, handler PlaybackEventHandler)

	// UnregisterEventHandler 注销事件处理函数
	UnregisterEventHandler(eventType PlaybackEventType, handler PlaybackEventHandler)

	// 生命周期管理

	// Initialize 初始化播放器
	Initialize() error

	// Close 关闭播放器并释放资源
	Close() error
}
